Summary

Under the Swoole and SwooleCoroutine adapters, multiple requests run concurrently in the same PHP process and share a single Http instance plus the static Router / Route / Hook registries. Today, per-request data is written onto those shared objects — when a coroutine yields on I/O, another coroutine clobbers it. This PR removes four such mutations and replaces the one valid use case with a race-free equivalent.

Races fixed

1. Http::$route — instance property holding "the current route." Two coroutines on the same Http overwrote each other; getRoute() and the telemetry attribution in run() saw the wrong route after any yield. Moved into the per-request context container (coroutine-local via Coroutine::getContext() in both Swoole adapters).
2. Route::$matchedPath — Router::match() mutated the singleton Route stored in Router::$routes via setMatchedPath(). Concurrent hits on the same route through different aliases / wildcard segments raced, breaking path-param extraction in execute(). Router::match() now returns the matched route alongside the prepared-path string in an immutable value class; the singleton is no longer mutated.
3. Http::$wildcardRoute — the wildcard branch did $route->path($path) on the singleton, so two concurrent wildcard requests fought over $path. Now we clone the wildcard route per request before stamping the URI.
4. Hook::setParamValue() writeback in Http::getArguments() — every resolved param value was written back onto the shared Hook/Route. Removed. Replaced with the per-request RouteMatch::$arguments map (see below).

The RouteMatch value class

Routing state — the matched Route, the prepared-path string it was matched under, and the name-keyed argument map — is one logical thing, so this PR bundles it into a single value class:

final class RouteMatch
{
    public function __construct(
        public readonly Route $route,
        public readonly string $path,
        public array $arguments = [],
    ) {}
}

$route and $path are immutable. $arguments is mutable so the framework can fill it in once the action's params resolve, without rebuilding the RouteMatch. Safe because the RouteMatch lives on the per-request context container (coroutine-local under Swoole), so only the request's own coroutine touches it.

Lifecycle:

• Router::match() returns ?RouteMatch (with empty $arguments).
• Http::match() stores it on the per-request context container under 'match' (or null if no match).
• Right before the route action runs, Http::execute() writes $arguments with the full resolved+validated argument map (path + query + body, post-validator) — same RouteMatch instance, no replacement on the context.
• The wildcard branch builds a RouteMatch around the cloned wildcard route.
• Telemetry attribution in run() reads it once at the end.

Note: $match->arguments is empty during init hooks — they run before the route's params are resolved. Surfacing path values into $arguments earlier (so init hooks can read URI segments like {databaseId} directly) is being tracked as a follow-up PR.

Terminology: resources vs. context

This PR formalizes a split that was already implicit in the codebase:

• Http::setResource() / Http::getResource() — singletons on the global container. Same as before.
• Http::setContext() (now public) — per-request values on the adapter's request container, which is coroutine-local under the Swoole adapters. Replaces the old setRequestResource() (protected, internal-only).

On the adapter, there is exactly one public reader:

• Adapter::getContext(): Container — returns the container for the current execution context. Inside a request, that's the per-request container (coroutine-local under Swoole), with parent-chain fallback to the global one for singleton lookups. Outside a request (boot, onStart hooks), it's the global container directly.

The global container is constructor-injected into the adapter and not retrievable post-construction. There is no public getContainer() — callers don't need to know which scope they're in; getContext() returns the right one for where they are.

The framework writes the following keys on the context container:

Inject match into any hook/action:

Http::shutdown()
    ->inject('match')
    ->action(function (RouteMatch $match) {
        // post-validation values, race-free under Swoole
        $template = $match->arguments['template'] ?? '';
    });

Breaking changes

This PR ships eight breaking changes. All are public-facing but localized.

1. Router::match() return type

Before: public static function match(string $method, string $path): ?Route
After: public static function match(string $method, string $path): ?RouteMatch

// Before
$route = Router::match('GET', '/users/123');
if ($route !== null) { /* ... */ }

// After
$match = Router::match('GET', '/users/123');
if ($match !== null) {
    $route = $match->route;
    $matchedPath = $match->path;
}

2. Http::getRoute() / Http::setRoute() removed

Both methods are gone. The current route is part of the RouteMatch value class on the context now.

• Read: $http->getResource('match')?->route or inject 'match'.
• Write: the framework sets the RouteMatch during match() / runInternal(); application code shouldn't.

3. Hook param values no longer populated by request handling

Http::getArguments() no longer calls $hook->setParamValue($key, $value). If you called $hook->getParamValue($key) or $hook->getParamsValues() from inside a route action / init / shutdown / error hook expecting it to return the resolved value for the current request, it will now return null.

Replacement: inject 'match' and read $match->arguments['key']. The framework populates this with the resolved+validated argument map right before the action runs, so shutdown / error hooks see the same values the action received. Race-free because the RouteMatch lives on the per-request context container (coroutine-local under Swoole), so only the request's own coroutine touches it.

// Before
$value = $hook->getParamValue('fileId');

// After (from a shutdown / error hook)
Http::shutdown()
    ->inject('match')
    ->action(function (RouteMatch $match) {
        $value = $match->arguments['fileId'] ?? null;
    });

init hooks see $match->arguments as empty — they run before the route's params are resolved. The full validated map is available from the action onward (and to all subsequent shutdown / error hooks). A follow-up PR will surface path values earlier so init hooks can read URI segments without falling back to Route::getPathValues().

4. Route::setMatchedPath() / Route::getMatchedPath() removed

These methods (and the underlying Route::$matchedPath property) have been deleted outright. Read it via $match->path.

5. Http::$requestContainer property removed

The protected ?Container $requestContainer = null; field was never assigned by the framework. Removed. If a subclass references it, drop the reference — per-request state lives on the adapter's context ($server->getContext()), which is coroutine-local in the Swoole adapters.

6. setRequestResource() renamed to setContext() (and now public)

Http::setRequestResource() (protected) is now Http::setContext() and is public — application code can use it to register per-request values, just as it already could with setResource() for singletons. Subclasses that overrode setRequestResource() need to rename their override (and widen visibility if they kept it protected). The Swoole adapters' coroutine-key constant REQUEST_CONTAINER_CONTEXT_KEY is likewise now CONTEXT_KEY, and the underlying string moved from '__utopia_http_request_container' to '__utopia_http_context'. If a subclass of either adapter referenced these, rename to match.

7. Adapter::getContainer() removed; replaced by getContext()

Adapter::getContainer() is gone. The adapter now exposes only getContext(): Container — a single public reader that returns the container for the current execution context (per-request inside a request with parent-fallback to global, global directly outside one). The global container stays constructor-injected and is not retrievable post-construction.

Custom Adapter subclasses must implement getContext() and drop their getContainer() implementation. Application code calling $server->getContainer() should switch to $server->getContext(); semantics match getContainer()'s old behavior (smart-routed by execution context), so a one-line rename is the whole migration.

8. Wildcard Route is now a per-request clone

The wildcard route inside RouteMatch for a wildcard handler is a per-request clone of Http::$wildcardRoute, not the singleton. Identity comparisons ($match->route === Http::$wildcardRoute) will fail. Property reads (getPath(), getAction(), etc.) behave identically.

Migration guide

For typical application code (defining routes, hooks, handlers), no changes are required unless you read the current route or used $hook->getParamValue(). The breaks only matter if you call the framework's routing primitives directly or subclass Http / the adapters.

If you run on FPM only, everything keeps working identically — there is no concurrency in FPM, so the races never fire and the new code paths are equivalent to the old ones.

Test plan

• vendor/bin/phpunit tests/HttpTest.php tests/RouterTest.php tests/RouteTest.php tests/RequestTest.php — 72/72 pass (added testShutdownHookCanInjectResolvedArguments covering the RouteMatch::$arguments flow).
• vendor/bin/phpstan analyse — clean at level 7.
• composer format:check — clean (Pint).
• e2e suite (ResponseFPMTest, ResponseSwooleTest) requires the swoole / fpm Docker hosts from docker-compose.yml; unchanged from main locally — verify in CI.
• Manual: hit a Swoole-backed deploy with concurrent requests against (a) the same parameterized route via different aliases, (b) the wildcard route from two clients in parallel, (c) a route whose handler awaits I/O and then reads getResource('match'), (d) a shutdown hook that injects 'match' and substitutes labels like {request.fileId} from $match->arguments.

🤖 Generated with Claude Code